<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Genres</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
  var popup = document.getElementById(material_id);
  popup.classList.toggle("show");
}
</script>

<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Genres' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inbuildn.html">Inbuild Modules</a></li><li><a href="index.html">supervisor</a></li><li><a href="index.html#2">Chapter 2: Conceptual Framework</a></li><li><b>Genres</b></li></ul></div>
<p class="purpose">The different sorts of work managed by inbuild.</p>

<ul class="toc"><li><a href="2-gnr.html#SP1">&#167;1. Genres</a></li><li><a href="2-gnr.html#SP6">&#167;6. Method functions</a></li></ul><hr class="tocbar">

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Genres.</b>Each different genre of work managed by Inbuild is represented by an instance
of the following structure. (At present, then, there are exactly seven
instances of it: nothing the user can do at the command line can change
that total.) A work unambiguously specifies what genre it has by means
of a non-null pointer to <span class="extract"><span class="extract-syntax">inbuild_genre</span></span>. Moreover, the rules for how Inbuild
manages works of this genre are expressed by methods attached to the structure.
For example, to copy a work, Inbuild calls the <span class="extract"><span class="extract-syntax">GENRE_COPY_TO_NEST_MTID</span></span>
method attached to its <span class="extract"><span class="extract-syntax">inbuild_genre</span></span>.
</p>

<p class="commentary">Each genre has its own section of code: for example, <span class="extract"><span class="extract-syntax">Kit Manager</span></span> defines
the instance <span class="extract"><span class="extract-syntax">kit_genre</span></span> and provides its method functions.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">genre_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">metadata_type_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">stored_in_nests</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">genre_class</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">method_set</span><span class="plain-syntax"> *</span><span class="identifier-syntax">methods</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax">;</span>

<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="function-syntax">Genres::new</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">Genres::new</span></span>:<br/>Extension Manager - <a href="4-em.html#SP2">&#167;2</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP1">&#167;1</a><br/>Kit Manager - <a href="4-km.html#SP1">&#167;1</a><br/>Language Manager - <a href="4-lm.html#SP1">&#167;1</a><br/>Pipeline Manager - <a href="4-pm.html#SP1">&#167;1</a><br/>Project Bundle Manager - <a href="4-pbm.html#SP1">&#167;1</a><br/>Project File Manager - <a href="4-pfm.html#SP1">&#167;1</a><br/>Template Manager - <a href="4-tm.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">md</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">nested</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">gen</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">gen</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">metadata_type_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">md</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">gen</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stored_in_nests</span><span class="plain-syntax"> = </span><span class="identifier-syntax">nested</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">gen</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_class</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">gen</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">methods</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Methods::new_set</span><span class="plain-syntax">();</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">gen</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Genres::name</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">Genres::name</span></span>:<br/>Copies - <a href="2-cps.html#SP3">&#167;3</a>, <a href="2-cps.html#SP11">&#167;11</a><br/>The Installer - <a href="7-ti.html#SP2_1">&#167;2.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">G</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"(none)"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">G</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Genres::metadata_type_name</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Genres::metadata_type_name</span></span>:<br/>Copies - <a href="2-cps.html#SP11">&#167;11</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">G</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"(none)"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">G</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">metadata_type_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure inbuild_genre is accessed in 2/ce, 2/rqr, 3/bg, 3/bs2 and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>Some genres of work, such as kits and extensions, can be stored in nests;
others, such as Inform projects, cannot. Whether a copy can be stored in a
nest depends only on its genre.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Genres::stored_in_nests</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">Genres::stored_in_nests</span></span>:<br/>Build Graphs - <a href="3-bg.html#SP10">&#167;10</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">G</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">G</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stored_in_nests</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>The requirements parser needs to identify genres by name, so:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="function-syntax">Genres::by_name</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">Genres::by_name</span></span>:<br/>Requirements - <a href="2-rqr.html#SP4_1">&#167;4.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">G</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq_insensitive</span><span class="plain-syntax">(</span><span class="identifier-syntax">G</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">))</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">G</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>When searching, treat these as equivalently good:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Genres::equivalent</span><button class="popup" onclick="togglePopup('usagePopup6')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup6">Usage of <span class="code-font"><span class="function-syntax">Genres::equivalent</span></span>:<br/>Requirements - <a href="2-rqr.html#SP7">&#167;7</a><br/>Extension Manager - <a href="4-em.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G1</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">G1</span><span class="plain-syntax"> == </span><span class="identifier-syntax">G2</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">G1</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_class</span><span class="plain-syntax"> != </span><span class="constant-syntax">0</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">G1</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_class</span><span class="plain-syntax"> == </span><span class="identifier-syntax">G2</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_class</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Genres::place_in_class</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">Genres::place_in_class</span></span>:<br/>Extension Manager - <a href="4-em.html#SP2">&#167;2</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">G</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre_class</span><span class="plain-syntax"> = </span><span class="identifier-syntax">c</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>For sorting of search results:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Genres::cmp</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">Genres::cmp</span></span>:<br/>Works - <a href="2-wrk.html#SP10">&#167;10</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G1</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">G2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">G1</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">G2</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"bad genre match"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">G1</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">allocation_id</span><span class="plain-syntax"> &lt; </span><span class="identifier-syntax">G2</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">allocation_id</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> -1;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">G1</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">allocation_id</span><span class="plain-syntax"> &gt; </span><span class="identifier-syntax">G2</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">allocation_id</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. Method functions.</b>And here are the method functions which a genre can, optionally, provide.
All of these act on a given work, or a given copy of a work, having the
genre in question.
</p>

<p class="commentary">First, this writes text sufficient to identify a work: e.g., "Locksmith
by Emily Short".
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_WRITE_WORK_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_WRITE_WORK_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_work</span><span class="plain-syntax"> *</span><span class="identifier-syntax">work</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>This looks at a textual file locator, which might be a pathname or a
filename, to see if it might refer to a copy of a work of the given genre.
If it does, an <span class="extract"><span class="extract-syntax">inbuild_copy</span></span> is created, and the pointer <span class="extract"><span class="extract-syntax">*C</span></span> is set to
point to it. If not, no error is issued, and <span class="extract"><span class="extract-syntax">*C</span></span> is left unchanged.
</p>

<p class="commentary">Errors can, however, be produced if Inbuild is pretty sure that the object
in the file system is intended to be such a copy, but is damaged in some way:
an extension with a malformed titling line, for example. Such errors are
attached to the copy for later issuing.
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_CLAIM_AS_COPY_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_CLAIM_AS_COPY_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> **</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ext</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">directory_status</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>This searches the nest <span class="extract"><span class="extract-syntax">N</span></span> for anything which (a) looks like a copy of a
work of our genre, and (b) meets the given requirements. If a genre does
not provide this method, then nothing of that genre can ever appear in
<span class="extract"><span class="extract-syntax">-matching</span></span> search results.
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_SEARCH_NEST_FOR_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_SEARCH_NEST_FOR_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_requirement</span><span class="plain-syntax"> *</span><span class="identifier-syntax">req</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">search_results</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>Some genres of work involve Inform source text &mdash; Inform projects and
extensions, for example. Reading in source text is fairly fast, but it's not
an instant process, and we don't automatically perform it. (When an extension
is scanned for metadata during claiming, only the opening line is looked at.)
</p>

<p class="commentary">This method should exist only for such genres, and it should read the source
text. It will never be called twice on the same copy.
</p>

<p class="commentary">Text should actually be read by feeding it into the lexer. Inbuild will take
of it from there.
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_READ_SOURCE_TEXT_FOR_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_READ_SOURCE_TEXT_FOR_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. </b>At the Graph Construction phase of Inbuild, each copy is offered the chance
to finalise its internal representation. For example, this may be when its
build graph is constructed, because we can now know for sure that there are
no further unsuspected dependencies.
</p>

<p class="commentary">This method is optional, and is called exactly once on every copy (whose genre
provides it) which has been claimed by Inbuild.
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_CONSTRUCT_GRAPH_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_CONSTRUCT_GRAPH_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;11. </b>This method is called when a copy is about to be built or have its graph
described, for example by <span class="extract"><span class="extract-syntax">-graph</span></span>, <span class="extract"><span class="extract-syntax">-build</span></span> and <span class="extract"><span class="extract-syntax">-rebuild</span></span>. Nothing actually
needs to be done, but if any work is needed before building can take place,
now's the time; and the vertex to build from can be altered by setting <span class="extract"><span class="extract-syntax">*V</span></span>.
(This is used to create upstream targets for Inform projects, such as the
blorbed release version. It affects <span class="extract"><span class="extract-syntax">-graph</span></span>, <span class="extract"><span class="extract-syntax">-build</span></span> and <span class="extract"><span class="extract-syntax">-rebuild</span></span> but
is ignored for other inspection options such as <span class="extract"><span class="extract-syntax">-use-missing</span></span>.)
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_BUILDING_SOON_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_BUILDING_SOON_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> **</span><span class="identifier-syntax">V</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>This duplicates, or syncs, a copy <span class="extract"><span class="extract-syntax">C</span></span> of a work in our genre, placing it
at a canonical location inside the given nest <span class="extract"><span class="extract-syntax">N</span></span>. In effect, it implements
the Inbuild command-line options <span class="extract"><span class="extract-syntax">-copy-to N</span></span> and <span class="extract"><span class="extract-syntax">-sync-to N</span></span>.
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_COPY_TO_NEST_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">INT_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_COPY_TO_NEST_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">syncing</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">build_methodology</span><span class="plain-syntax"> *</span><span class="identifier-syntax">meth</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>This writes documentation on the edition (if it provides any).
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_DOCUMENT_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">VOID_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_DOCUMENT_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dest</span><span class="plain-syntax">, </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sitemap</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. </b>This performs some sort of automatic-update to the latest format:
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">GENRE_MODERNISE_MTID</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">INT_METHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">GENRE_MODERNISE_MTID</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">)</span>
</pre>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="1-ic.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-sm.html">1</a></li><li class="progresscurrentchapter">2</li><li class="progresscurrent">gnr</li><li class="progresssection"><a href="2-wrk.html">wrk</a></li><li class="progresssection"><a href="2-edt.html">edt</a></li><li class="progresssection"><a href="2-cps.html">cps</a></li><li class="progresssection"><a href="2-ce.html">ce</a></li><li class="progresssection"><a href="2-rqr.html">rqr</a></li><li class="progresssection"><a href="2-nst.html">nst</a></li><li class="progresssection"><a href="2-rgs.html">rgs</a></li><li class="progresssection"><a href="2-jm.html">jm</a></li><li class="progresssection"><a href="2-lcn.html">lcn</a></li><li class="progresschapter"><a href="3-bg.html">3</a></li><li class="progresschapter"><a href="4-em.html">4</a></li><li class="progresschapter"><a href="5-es.html">5</a></li><li class="progresschapter"><a href="6-st.html">6</a></li><li class="progresschapter"><a href="7-tm.html">7</a></li><li class="progressnext"><a href="2-wrk.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

